package com.bubblegumproject.ogo.action;

import com.bubblegumproject.ogo.component.Container;

/**
 * A <code>Flow</code> is a component that knows how to handle specific {@link Action} objects. A <code>Flow</code>
 * usually encapsulates pure process logic; it relies on other components and objects to actually perform application
 * logic. A Flow component should usually expose {@link com.bubblegumproject.ogo.component.ActionHandler} methods that
 * take various Action classes.
 *
 * @author Azubuko Obele (buko.obele@gmail.com)
 */
public interface Flow {

    /**
     * Determine whether a Flow is finished. A Flow, like other Components, has state and may require a sequence of
     * Action objects to be received before it's finished and can be safely stopped.
     *
     * XXX: This is just wrong and it overcomplicates things a lot. We can simplify this by making it a rule that Flows
     * always are always considered finished after processing an Action and that they are then destroyed. Flows that
     * handle multiple Actions are just wrong. I
     *
     * @return <code>true</code> iff the Flow is finished and has received a valid sequence of actions
     */
    public boolean isFinished();

    /**
     * Context containing various contextual information for the life of the Flow. Note that a Flow is
     * generally responsible for creating its own <code>Context</code> object which should usually inherit the Context
     * object of its parent Flow..
     *
     * @return Context containing various objects that will exist for the lifetime of the Flow
     */
    public Context getContext();

    public void setContext(Context context);

    public Container getContainer();

    public void setContainer(Container container);

    /**
     * Get the parent Flow. Flow objects usually have a parent Flow which created and activated the given Flow. This is
     * usually the {@link Agent} that activated the Flow but it may be another Flow that is using the Flow as a subflow.
     *
     * XXX: Why does a Flow need a reference to its parent? This is almost certainly wrong. Children should never know
     * about their parents! Get rid of this!
     *
     * @return parent Flow
     */
    public Flow getParent();

}
